8.4. Documentation
What builds this site?
The root project pins Zensical exactly:
Zensical is pre-1.0, so every upgrade must rebuild and visually inspect the complete site. uv.lock records its exact transitive environment.
Why is configuration in mkdocs.yml?
The pinned Zensical version reads mkdocs.yml. The file enables strict mode, explicit navigation for every page, non-directory URLs, Material navigation/search/code features, Mermaid fences, admonitions, repository edit links, social links, and the custom stylesheet.
Explicit navigation prevents a new cloud profile or asset from silently reordering the learning path.
pymdownx.snippets is rooted at the repository, checks every include path, forbids traversal outside the base, and dedents marked subsections. Critical examples therefore come from named regions in agents/python/src/agent/ instead of drifting copies in Markdown.
What does the structural checker enforce?
Before rendering, scripts/check-docs.sh requires each docs/**/*.md page to:
- start with
descriptionfront matter; - contain at least one H2;
- express every H2 as a question;
- contain no machine-specific path or retired registry hostname.
Zensical then validates Markdown/navigation in strict mode, and mise run check:links checks repository-local Markdown links without network access. A successful HTML render alone is not enough.
How do you preview and build?
mise run serve # live preview at http://localhost:8000
mise run build # static site under site/
mise run check:docs
mise run check:links
Review desktop/mobile navigation, Mermaid diagrams, tables, code copy, admonitions, internal links, and long headings in the rendered site.
What does the Pages workflow actually guarantee?
On a push to main, .github/workflows/docs.yml installs the pinned mise toolchain and runs mise run check:docs. It uploads and deploys the Pages artifact only when GitHub reports that Pages is enabled for the repository; otherwise the workflow records a notice and stops after validation.
A green workflow proves the source builds. It does not by itself prove that the repository is anonymously readable, the Pages setting is correct, DNS resolves, TLS is valid, or every deployed/source link works.
What is the publication gate?
Before the README advertises a hosted course, verify from a clean unauthenticated environment:
- Anonymous Git access can resolve and clone the repository.
- The deployed homepage and a deep chapter URL return successful HTTPS responses.
- The custom domain resolves to the intended Pages host and presents a valid certificate.
- Repository edit/source links open without maintainer credentials.
- Every link in the built site passes an online link check.
One reproducible release check is:
CLEAN_HOME="$(mktemp -d)"
GIT_CONFIG_NOSYSTEM=1 GIT_TERMINAL_PROMPT=0 HOME="$CLEAN_HOME" \
git -c credential.helper= ls-remote \
https://github.com/MLOps-Courses/agentops-open-course.git HEAD
rm -rf "$CLEAN_HOME"
curl -fsS https://agentops-open-course.fmind.dev/ >/dev/null
curl -fsS \
'https://agentops-open-course.fmind.dev/8.%20Community/8.7.%20Capstone.html' \
>/dev/null
lychee --no-progress 'site/**/*.html'
Run this only after mise run check:docs has generated site/. If any command fails, the verified surface remains the local preview and the release is not publication-complete.
How is the custom domain declared?
docs/CNAME and site_url declare the intended agentops-open-course.fmind.dev address. They are configuration, not evidence that DNS or Pages is active. DNS, the GitHub Pages repository setting, the deployed artifact, and certificate status must agree before the URL is presented as working.
What is the documentation checkpoint?
Run mise run check:docs and mise run check:links, follow all changed pages in the local preview, confirm critical snippets render from source, and inspect the generated site/CNAME. For a publication release, run the anonymous gate above from outside any maintainer-authenticated browser/session. Do not advertise or deploy manually from an unvalidated working tree.